The EptDataSource control allows databinding against an ept category. It can be used to quickly output a list of values from an ept category without using any manually written code.

Background

A need for a datasource that could handle ept documents arose when new sites was developed without Active Scripting components. One commonly used solution was to read the data with code and expose it to a databound control. The EptDataSource control fills this need by providing a derived DataSourceControl that can be used against an ept category and supports all data management methods; create, read, update and delete.

Configuration

There are two required settings; CategoryId and Fields. CategoryId needs to be set to the category that the EptDataSource should work with, and Fields is a string array containing the name of all ept fields that should be used. There are two fields that are always returned, and can not be removed; documentid and filename. These ensure that the EptDataSource control can always save data back to Content Studio if requested.

The EptDataSource control reads information needed to communicate with Content Studio from the current web request automatically. This will not work if the control is used outside of a Content Studio site. You will then need to set the extended configuration properties ConnectionId and UserSessionId.

Sorting

The EptDataSource control has built-in support for sorting using the SortCommand property. A databound control can override by specifying the DataSourceSelectArguments.SortExpression when querying the datasource for data.

Creating and updating documents

The EptDataSource control does not require any extra configuration when creating new documents. It will, with the default setup, create documents in the same category as documents are read from, and will not approve the document.

Extended configuration

The EptDataSource control also provides the functionality to set configuration settings with the different parameter collections; SharedParameters, SelectParameters, UpdateParameters, DeleteParameters and InsertParameters. These can be used to bind configuration settings to control values using the ControlParameter class. The parameter name should be the same as the property name you want to use. Note that it is possible to specify different settings for different parameters, allowing all selections to be made from one category, but inserted into another.

It's possible to apply a filter to the data selection process by setting the FilterCriteria property. The value used will be passed to the XmlFilter.FilterCriteria.

List of configuration settings

Some of these settings can be specified as properties on the EptDataSource control. All of these settings can also differ between the different parameter collections creating configurations that read from one category and creating new documents in another.

CategoryId A category id. This is only used when reading and creating documents.
ConnectionId A connection id. This will be read from the current http request if possible.
ContentToLoad Specifies if drafts, approved content, or both, should be returned. Default is both approved content and drafts. Only used when reading documents.
DocumentTitleFieldName The field that should be used as document title when creating new ept documents. Default is a guid value. Only used when creating documents.
EnableApprove Determines if the document should be approved after it has been updated or created. Default is false. Only used when creating and updating documents.
Fields A list of fields.
FilterCriteria A filter that will be applied when reading documents. Default is an empty string. Only used when reading documents.
PageNumber Current page number. Rarely used, most databound controls override this. Only used when reading documents.
PageSize Number of items per page. Rarely used, most databound controls override this. Only used when reading documents.
SortCommand Default sort order if none is provided by the databound control. Default is an empty string. Only used when reading documents.
UserSessionId A session id. This will be read from the current http request if possible.

Examples

The following code would work against the CS_CreatedDate, FirstName, LastName and Username fields in the Data/Members category. Data read will be sorted by the Username field ascending. Creating, updating and deleting documents will work.

HTML 
<csx:EptDataSource RunAt="Server" Id="dsMembers" CategoryId="Data/Members"
                   Fields="CS_CreatedDate,FirstName,LastName,Username" SortCommand="[Username] ASC" />

The following code has the same functionality, but has its configuration set as extended configuration with the different parameter collections.

HTML 
<csx:EptDataSource RunAt="Server" Id="dsMembers">
  <SharedParameters>
    <asp:Parameter Name="CategoryId" DefaultValue="Data/Members" />
    <asp:Parameter Name="Fields" DefaultValue="CS_CreatedDate,FirstName,LastName,Username" />
    <asp:Parameter Name="SortCommand" DefaultValue="[Username] ASC" />
  </SharedParameters>
</csx:EptDataSource>

The EptDataSource control can be configured to read approved content (ContentToLoad) while saving new information as drafts (this is default). This will enable a business logic that requires another process to approve the content before it's possible to read it.

HTML 
<csx:EptDataSource RunAt="Server" Id="dsMembers">
  <SharedParameters>
    <asp:Parameter Name="CategoryId" DefaultValue="Data/Members" />
    <asp:Parameter Name="Fields" DefaultValue="CS_CreatedDate,FirstName,LastName,Username" />
    <asp:Parameter Name="SortCommand" DefaultValue="[Username] ASC" />
    <asp:Parameter Name="ContentToLoad" DefaultValue="Approved" />
  </SharedParameters>
</csx:EptDataSource>

Another configuration scenario is when the business logic requires that new content needs to be approved by another process, while updated content is approved automatically. We only need to change the settings for the UpdateParameters since EnableApprove is false by default.

HTML 
<csx:EptDataSource RunAt="Server" Id="dsMembers">
  <SharedParameters>
    <asp:Parameter Name="CategoryId" DefaultValue="Data/Members" />
    <asp:Parameter Name="Fields" DefaultValue="CS_CreatedDate,FirstName,LastName,Username" />
    <asp:Parameter Name="SortCommand" DefaultValue="[Username] ASC" />
    <asp:Parameter Name="ContentToLoad" DefaultValue="Approved" />
  </SharedParameters>
  <UpdateParameters>
    <asp:Parameter Name="EnableApprove" DefaultValue="true" />
  </UpdateParameters>
</csx:EptDataSource>